A.C.E. 2

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 2 / ACE CD 2.iso / FILES / DOCS / AMOSCOMP.LHA / AmosCompiler.doc next >

Wrap

Text File | 1994-11-27 | 95.3 KB | 2,165 lines

\ \\ \\\ \ \\ \ \\\ / \ _____ \\\\ / \ ____ \ \ \\\ \ / /\ ) / / \ \ \ \/ / \ / / / \ \ \ / \/ / / \ \ \ / / / \ \ \ / _________/ / \ \ \/ / ______ / \ \_________ / / / / \ \ / (_____/ / \_____________)(____________/[PAZZA] P R E S E N T THE AMOS COMPILER INSTRUCTIONS Typed by SIDEWINDER of LSD. Manual Supplied by TORCH (The man in the floppy hat!) CHAPTER 1: OMITTED as its just a description of AMOS etc. CHAPTER 2: QUICK START By the time you're reading this, you'll probably be raring to go! Don't be too impatient though. You'll need to install the compiler onto a working COPY of your AMOS program disk. The whole process takes about 10 minutes, but thankfully it only needs to be done once. Here's a quick run-down of the general technique. o Make an immediate back-up of the Compiler disk on a freshly formatted disk. o Now place your new copy of the AMOS Compiler disk into the internal drive, and boot up your Amiga in the normal way. After a few short moments, the AMOS Installation program will be executed, and you'll be presented with the following screen: +-------------------------------------+ | A M O S C O M P I L E R | +-------------------------------------+ | +-----------------+ | | | R E A D M E | | | +-----------------+ | | +-----------------+ | | | U P D A T E | | | +-----------------+ | | +-----------------+ +---------+ | | | I N S T A L L | | E X I T | | | +-----------------+ +---------+ | +-------------------------------------+ Notice the three large icons to the left of the screen. These can be selected by simply clicking on them with the left mouse button. To reach the point where you can start compiling, follow the three main steps: 1 READ ME Displays a complete explanation of the compiler installation along with a full list of any updates or changes to the compiler. It's a good idea to read this very carefully before continuing. (Use the mouse to move up and down the text file.) 2 UPDATE (see chapter 3) Updates your current version of AMOS Basic to the latest version using the supplied Updater disk. NOTE: The AMOS Compiler will only work with versions of AMOS Basic from 1.3 upwards. So if you're using an earlier version, it's essential to upgrade immediately using the updater included. You'll now need to insert a COPY of your AMOS program disk at this point. WARNING! - DON'T UPDATE THE ORIGINAL AMOS PROGRAM DISK! The updater will automatically delete any existing AMOS programs to make room for the new version. Use a back-up copy instead. 3. INSTALL (see chapter 4) Installs the compiler extension onto a copy of your AMOS program disk. As mentioned previously, the compiler should only be installed on versions of AMOS from 1.3 onwards. CHAPTER 3: UPDATING TO AMOS VERSION 1.3 The AMOS compiler should only be used with AMOS V1.3 or higher. There's no need to worry if you've got a previous version. We've helpfully included a free update to AMOS V1.3 along with this compiler. If you've been using the original AMOS V1.1 all this time, you should notice a number of significant improvements (see the What's new in V1.3 supplement). Here's the procedure in detail, for updating to version 1.3: o The first job you must do is create a copy of your AMOS programs disk (see Making a back-up). Once you've created a new AMOS Programs disk and have it tested works, you'll be ready to update this disk to 1.3. o Place the AMOS Compiler disk into the internal drive and turn on your Amiga. The Compiler Installation program will automatically load into memory and the following welcome screen will be displayed: +--------------------------------------+ | A M O S C O M P I L E R | +--------------------------------------+ | +-----------------+ | | | R E A D M E | | | +-----------------+ | | +-----------------+ | | | U P D A T E | | | +-----------------+ | | +-----------------+ +---------+ | | | I N S T A L L | | E X I T | | | +-----------------+ +---------+ | +--------------------------------------+ o Now insert the AMOS Updater disk into any drive and select the Update button with the left mouse button. o The AMOS Updater program will be loaded and a new screen will be displayed: +-----------------------------+ | A M O S 1.3 U P D A T E | +-----------------------------+ | +-------------+ | | | U P D A T E | | | +-------------+ | | +---------+ | | | E X I T | | | +---------+ | +-----------------------------+ o The process of updating is completely automatic. If you want to update to a hard disk though, you'll have to update a floppy disk first and then copy across the relevant files (see below). o WARNING! The updater will automatically delete any non-essential program files from the backed-up AMOS disk! So it's vital to ensure that you've made a copy of the AMOS program disk and are not using the original AMOS master. o Start the updater by pressing the left mouse button when the pointer is over the Update icon. o You'll be prompted to insert the copy of the AMOS Program disk (the one you prepared earlier) into any available drive. If you've an external drive, you should keep the Updater disk in Df:0 and place the program disk into the external drive. This will avoid the need to do any laborious disk swapping. (For unexpanded A500 users, There are only 12 disk swaps during this process.) Your AMOS program disk will be updated to AMOS 1.3. Once the update is complete, select the EXIT button and you'll be asked to insert the compiler disk. Upon responding to this you'll be returned straight to the main welcome screen. Before continuing, you are strongly recommended to make an immediate back-up of the new system onto a fresh disk. See 'Making a back-up' for more details. INSTALLING AMOS V1.3 ONTO A HARD DISK o Follow the above procedure so that you have a copy of V1.3 on a floppy disk. o Boot up your Amiga from your hard disk as normal. o Enter the CLI or SHELL. o Insert your new copy of AMOS 1.3 into the internal drive. o Set the directory to the internal drive: o You can now type the following line from the CLI prompt (note the space between AMOS1.3 and the filename INSTALL.AMOS: o AMOS will load into memory and you'll be presented with the hard disk installation program automatically. This program will be requesting you to select an option from the main menu. o Pull down the INSTALLATION menu by pressing the RIGHT mouse button and highlighting the Installation text. o From the resulting menu list, move the mouse over the AMOS MASTER DISK ENTRY. This will produce another menu list associated with installing files from the AMOS1.3 master to the hard disk. o Select the JUST INSTALL AMOS option from the menu. o When the file selector appears and requests you to select the drive you wish AMOS1.3 installed onto, first use the right mouse button to change the directory list into a DRIVE list. o From the DRIVE list that appears, select the one you want AMOS1.3 installed onto by highlighting the drive name and clicking on the LEFT mouse button. o The files on the selected drive will now be listed in the file selector. When you're happy you've selected the right drive, click with the left mouse button on the file selector's OK button. o Now wait for the installation to finish. o When the installation is complete, automatic amendments to the hard disk startup-sequence can be performed. Unless you know what this means (read below) we strongly advise that you avoid this option and select QUIT at this point. o If you want to append a new assign command to your startup-sequence, then use the file selector to find the startup-sequence you wish to add the line to, select it with the left mouse button and click on OK. Inserting an assign means that every time you boot your hard disk, the use of AMOS at the start of a filename will inform AmigaDos of where AMOS is located on the hard disk. For example: assign AMOS_DATA: WORK:AMOS_Discs/Data_disc This will set up AmigaDos so that use of AMOS_DATA will always look on the hard disk partition WORK: and inside the folder path AMOS_Discs/Data_disc. In other words: dir AMOS_DATA: is the same as typing: dir WORK:AMOS_Discs/Data_disc A word of warning though: You must be sure the startup-sequence you select is used by the system to boot up. You must also be sure it doesn't finish its work before it reaches the new assign at the end of the startup- sequence. If you're unsure about the whole idea, simply select Quit at this option is not essential. CHAPTER 4: INSTALLING THE COMPILER Now that you have an AMOS programs disk containing the new version, you'll need to install a special extension of commands onto it. This extension adds new commands to AMOS (similar to the Compactor, Requester and Serial extensions). o If you already haven't upgraded to AMOS Version 1.3, now's the time to do so. Jump back to the previous chapter on UPGRADING TO AMOS 1.3. The installation procedure is straightforward: o If using floppy disks, place a COPY of your Compiler disk into the internal drive, and re-boot your Amiga. The WELCOME program will now load into memory. o Hard disk users should boot from their hard disk, insert the Compiler disk into DF0: and double click on the disk icon. When the window has displayed the programs on the disk, double click on the WELCOME icon. +-------------------------------------+ | A M O S C O M P I L E R | +-------------------------------------+ | +-----------------+ | | | R E A D M E | | | +-----------------+ | | +-----------------+ | | | U P D A T E | | | +-----------------+ | | +-----------------+ +---------+ | | | I N S T A L L |<--+ | E X I T | | | +-----------------+ | +---------+ | +-----------------------|-------------+ | o You are now ready to install the AMOS compiler extension file onto your new AMOS program disk. o Select the Install icon with the mouse and click once on the left button. This will automatically load a separate Installation program from the disk. +--------------------------------+ | A M O S C O M P I L E R | +--------------------------------+ | +-----------------+ | | | I N S T A L L | | | +-----------------+ | | +---------+ | | | E X I T | | | +---------+ | +--------------------------------+ o This screen allows you to choose between several possible machine configurations. These allow you to customise the compiler to your own particular system. Each option can be selected by simply clicking on the relevant text with the left mouse button. o Before proceeding with the Installation, the program will carefully explain the pros and cons of the relative configuration. If the chosen setting is not to your liking, you can return to the previous menu by selecting the ABORT button. The final choice is entirely up to you. You can, for instance, safely use the unexpanded A500 setting on machines with a megabyte or more of memory. You can create a range of different compiler disks to cope with various programming requirements. o When you have decided which configuration to use, simply click on the relevant text. o Floppy disk users will be asked to insert their new AMOS programs disk into any drive. o Hard disk users are presented with a file selector. From this you must double click on the AMOS1.3 file located on the hard disk. This then informs the installer where to do the installation. o Follow the prompts at the bottom of the screen for a successful install. CHAPTER 5: COMPILER TUTORIAL The best way of getting to know the compiler is to have a go at using it. To do this, we'll guide you through the easy process of compiling one of the example programs from the AMOS compiler disk. Two of the tutorials (1 meg systems with floppy drives) require you to have a blank formatted disk prepared. So if you haven't one handy prepare it now. As our starting point, let's make sure that the compiler has been installed properly. o Boot up AMOS and check that the compiler extension is in memory. If it is, COMPILER EXTENSION V1.00 should be listed on the screen: +--------------------------------------------------+ | Version 1.3 | +--------------------------------------------------+ | | | +-----------------------------+ | | | | | | | AMOS The Creator | | | | | | | | by Francois Lionet | | | | (c) 1990 Mandarin/Jawx | | | | | | | +-----------------------------+ | | | | Music extension V1.3 | | Picture compactor V1.2 | | Requester V1.3 | | Compiler extension V1.00 | | | +--------------------------------------------------+ o If this message is not on your screen, refer back to the quick start section. It will explain the three steps you must take to reach this point. o Now place the AMOS compiler disk into any drive and load the file 3D_Cube.AMOS from the EXAMPLES folder. o We'll first this example program running in standard interpreted AMOS Basic. Click on RUN to see it in action. o If you've had to remove the AMOS programs disc, you'll find that AMOS requests this disk to be re-inserted. This is because the program it is running requires important maths routines from the disk. o When the cube appears on the screen, press the 3, 7 and 9 keys on the numeric keypad. This will spin the cube in 3D! Repeated pressing on the numbered keys will spin the cube faster. o To stop the program press Control-C. o Go back to the AMOS Editor. Before you go any further, it's very important to remember what types of compiler installation process was used. If you're using extra memory, extra drives or a hard drive you must use the correct tutorial listed below. THE UNEXPANDED AMIGA 500 WITH ONE OR TWO DISK DRIVES o With the 3d_cube.AMOS program still in memory, you should now test the program by pressing F2 or by selecting this option with the mouse. This is very important as you cannot compile a program that has not been previously tested. o Save the tested AMOS program as CUBE.AMOS to the AMOS programs disk. o Load the program.COMPILER.AMOS from the programs disk and RUN it. o Since the process of compilation on the unexpanded Amiga is entirely disk based, it is very important to check that the compiler has been set up correctly. On the menu screen you should note two disk icons which represent the source and destination of the program to be compiled. You should also note the Workbench icon on the far right of the screen - this specifies that the compiled program is to be run from the Workbench. o Now here comes the exciting bit! Select the compile icon with the mouse. You should now be presented with the usual AMOS file selector from which you should select Cube.AMOS. o After telling the computer which program you want to compile, you must then inform it of the filename it must use to create the compiled version. For now, simply click on O.K. and the compiler will take the source name (3D_Cube.AMOS) and create a destination file called 3D_Cube. o The progress of the compilation is depicted by yellow arrows moving left to right across the screen. If the compiler has no problems compiling, it will finish its work when all the yellow arrows have lit up. o Now it's time to run the compiled program. Because a Workbench type of file was selected you'll have to first re-boot the Amiga with your Commodore Workbench disk in the internal drive. o When Workbench is displayed, insert the AMOS programs disk, double click on its icon representing Cube. o Single drive users will be requested to re-insert their Workbench disk prior to the program fully running. This is so that the program can access libraries from the boot disk. o All being well, the newly compiled program will appear and the speed at which it operates will show you the compiler's real worth. o Welldone! THE EXPANDED AMIGA (1 MEGABYTE+) WITH ONLY ONE DRIVE o Ensure you have a formatted blank disk prepared for this tutorial. this is where our compiled program will be placed. o With the 3d_cube.AMOS program still in memory, you should now test the program by pressing F2 or by selecting this option with the mouse. This is very important as you cannot compile a program that has not been previously tested. o Save the tested AMOS program as CUBE.AMOS to the previously formatted disk. o Load the program Compiler.AMOS from the programs disk and RUN it. o Since the process of compilation on the expanded Amiga is entirely RAM based, it is very important to check that the compiler has been set up correctly. On the menu screen you should note two RAM icons which represent the source and the destination of the program to be compiled. You should also note the AMOS icon on the far right of the screen - this specifies that the compiled program is to be run from AMOS. o At this point, all the library routines that the compiler accessory uses are transferred to the RAM disk, utilising the full capabilities of your expanded machine. o Insert the disk with Cube.AMOS on it, into the internal drive. o Now here comes the exciting bit! Select the compile icon with the mouse. You will now be presented with the unusual AMOS file selector from which you should select CUBE.AMOS. o After telling the computer which program you want to compile, you must then inform it of the filename it must use to create the compiled version. For now, simply click on O.K. and the compiler will take the source name (3D_CUBE.AMOS) and create a destination file called 3D_Cube_C.AMOS. o The progress of the compilation is depicted by yellow arrows moving left to right across the screen. If the compiler has no problems compiling, it will finish its work when the yellow arrows have lit up. o Now it's time to run the compiled program. Select the Exit icon with the mouse and return to the AMOS Editor. o Now load in the compiled program 3D_Cube_C.AMOS and run it. o All being well, the newly compiled program will appear and the speed at which it operates will show you the compiler's real worth. o Welldone! THE EXPANDED AMIGA (1 MEGABYTE+) WITH TWO DISK DRIVES o Ensure you have a formatted blank disk prepared for this tutorial. This is where our compiled program will be placed. o With the 3d_cube.AMOS program still in memory, you should test this program by pressing F2 or by selecting this option with the mouse. This is very important as you cannot compile a program that has not been previously tested. o Insert the blank formatted disk into the external drive. o Save the tested AMOS program as CUBE.AMOS to the blank disk in the external drive. o Load the program Compiler.AMOS from the programs disk and RUN it. o Since the process of compilation on the expanded Amiga is entirely RAM based, it is very important to check that the compiler has been set up correctly. On the menu screen you should note two RAM icons which represent the source and the destination of the program to be compiled. You should also note the AMOS icon on the far right of the screen - this specifies that the compiled program is to be run from AMOS. o Now here comes the exciting bit! Select the compile icon with the mouse. You will now be presented with the usual AMOS file selector from which you should select CUBE.AMOS. In this case you'll have to first make the file selector display the contents of the disk in the external drive. To do this, click the right mouse button to display the available drives. o After telling the computer which program you want to compile, you must then inform it of the filename it must use to create the compiled version. For now, simply click on O.K. and the compiler will take the source name (3D_CUBE.AMOS) and create a destination file called 3D_Cube_C.AMOS on the same disk. o The program is depicted by yellow arrows moving left to right across the screen. If the compiler has no problem compiling, it will finish its work when all the yellow arrows have lit up. o Now it's time to run the compiled program. Select the Exit icon with the mouse and return to the AMOS Editor. o All being well, the newly compiled program will appear and the speed at which it operates will show you the compiler's real worth. o Welldone! ANY AMIGA (1 MEGABYTE+) WITH A HARD DISK o Hello hard disk users (you lucky guys). Compiling on the hard disk is easy and extremely fast. o With the 3d_cube.AMOS program still in memory, you should now test the program by pressing F2 or by selecting this option with the mouse. This is very important as you cannot compile a program that has not been previously tested. o Save the tested AMOS program as CUBE.AMOS to the hard disk. o Load the program Compiler.AMOS from the hard disk and RUN it. o Since the process of compilation on the expanded Amiga is entirely disk based, it is very important to check that the compiler has been set up correctly. On the menu screen you should note two disk icons which represent the source and the destination of the program to be compiled. You should also note the AMOS icon on the far right of the screen - this specifies that the compiled program is to be run from AMOS. o Now here comes the exciting bit! Select the compile icon with the mouse. You will now be presented with the usual AMOS file selector from which you should select CUBE.AMOS. o After telling the computer which program you want to compile, you must then inform it of the filename it must use to create the compiled version. For now, simply click on O.K. and the compiler will take the source name (3D_CUBE.AMOS) and create a destination file called 3D_Cube_C.AMOS. o The process of the compilation is depicted by yellow arrows moving left to right across the screen. If the compiler has no problems compiling, it will finish its work when all the yellow arrows have lit up. o Now it's time to run the compiled program. Select the Exit icon with the mouse and return to the AMOS Editor. o Now load in the compiled program 3D_Cube_C.AMOS and run it! o All being well, the newly compiled program will appear and the speed at which it operates will show you the compiler's worth. o Welldone! CHAPTER 6: USING THE COMPILER Although the compiler works best on an expanded machine, it has been carefully designed to produce superb results with even the smallest machines. It comes complete with a number of powerful memory saving options, which allow you to compile massive programs on any Amiga from an unexpanded A500 to the latest A3000 system. In order to make the most out of the compiler, you'll need to tailor the package to suit your own precise systems configuration. Just to make life easier for you, here's a detailed list of the various possibilities. ON A HALF MEG A500 First, the good news! The AMOS compiler will work fine on your system, and there will be absolutely no restrictions on the size of the programs you will able to compile. In fact, because of its advanced memory conservation features, the compiler will even cope with programs which would never have squeezed into the original interpreter! The compiler can be executed straight from AMOS Basic using the COMPILER.AMOS accessory. This can be entered into memory with either the Load or Load Other commands from the editor. Although memory will be pretty tight, you will still be able to compile and run most programs without ever having to leave the AMOS system. Compiled programs can be executed directly from the Editor, just like the interpreted versions. So there are no complicated new commands to remember. The compiler provides a range of options which allow you to reduce the memory consumption to the absolute minimum. The biggest savings can be accomplished by setting both the Source and Destination icons to Disk from the compiler accessory. It's also possible to ignore the accessory entirely and compile your programs from direct mode. Since the compiler only works with tested programs, you should first check the current program for errors using the Test option from the editor (F2). You can then save your program onto the disk using Amiga-S or by selecting the Save option from the main menu. Hit the Esc key to enter Direct mode and type: AMOS>Screen Close 0 This will force the compiler messages to be displayed in the Direct mode window, saving 32k of memory. Compile your program with: AMOS>compile "prog.amos -D11 -T3" PROG.AMOS is the name of your program. It could obviously be anything you like. The D11 bit activates the compiler's memory conservation feature and writes your program straight to the disk. T3 saves the program in .AMOS format. You'll now be able to enter it into AMOS Basic using a simple Load command from the editor. As it's compiled, your new program will automatically be saved under the filename such as 'prog'. Finally, you can load and run the compiled program straight from AMOS Basic with Run (F1). You can also execute the program immediately from the command line with: AMOS>Run "prog" ON AN UNEXPANDED SINGLE DRIVE MACHINE As a default, the compiler expects to find a series of library files in the AMOS_System folder of the current disk. The installation routines will automatically free up as much space as possible on your working compiler disk. You'll now be left with around 350k to hold your programs and data. Hopefully, this should be more than sufficient for the vast majority of applications. ON AN UNEXPANDED TWO DRIVE MACHINE In this case, you can simplify matters considerably by using a separate disk to hold your programs and data. The compiler disk should now be placed in the internal drive, and the program data disk in DF1:. You now have more than enough space to compile even the largest AMOS programs with consummate ease. WITH A MEGABYTE OF MEMORY On an expanded machine, you'll be able to hold both the compiled and interpreted versions of your programs simultaneously in memory. So whenever a problem occurs in one of your compiled programs, you can now jump straight back to your original interpreted program and correct it immediately. The compiled program is stored just like any other AMOS Basic program and can be called straight from the editor. It's therefore possible to flick effortless between the interpreted and compiled versions of the program in a matter of seconds. The compiler accessory is intelligent and makes full use of any extra memory you've installed in your system. At the start of the session, the compiler accessory automatically copies all the compiler libraries onto a super fast RAM disk. Once these libraries have been loaded into memory, they will be permanantly available to the compiler. So the next time you enter the accessory, it will be immediately ready for use. Another advantage of this system, is that there's no need to keep a copy of the compiler disk in the current drive. If you've got a single drive you can therefore store all your programs and data on a completely separate disk. This can be placed in the internal drive ready for use at a moment's notice. The resulting speed increases have to be seen to be believed! You can, for instance, compile the 500-line Amosteriods program from the AMOS Data disk in well under 20 seconds! Surprisingly enough, this figure includes the time spent loading and saving the program to the disk. Usually, you'll be able to compile your programs directly into memory using the default compiler settings. However, if your program is especially large, you may need to activate one of the compiler's many built-in memory conservation features. These can be selected by clicking on the Source and Destination icons on the accessory screen. If you are unsure about this, see the section on the Compiler accessory for a detailed explanation. Try changing the Source option first. This will save you a fair amount of memory, and is capable of compiling your programs reasonably quickly. If all else fails, simply set both the source and destination set to Disk. It's not the end of the world, of course. You'll still be able to compile most programs in under two minutes! WITH A MEGABYTE OF MEMORY AND TWO DRIVES In addition to the previous option, you can keep the boot disk permanently in the internal drive, and store your programs on a separate disk in drive two (Df1:). This is ideal if you are only intending to use the compiler occasionally basis, since it reduces the memory overhead to a mere 2k. You'll now be left with the maximum possible space to hold your programs and data. On the other hand, the compilation will be slowed down considerably, as the system will now be forced to read the compiler libraries directly from disk. You can of course, easily create separate AMOS program disks for each possible configuration. You can then boot up a different version of AMOS Basic depending on your current programming requirements. ON A HARD DISK Actually, there's not much to say. As you would expect, the AMOS compiler will perform superbly on your system, and you'll be able to compile even the largest problems with consummate ease. The installation program will automatically place all the required files on your hard disk. After that, you can simply run AMOS Basic and go! The compiler libraries can be kept on the hard disk, or loaded into RAM disk as required. Because of the speed of your hard disk, there's not a great deal of difference! You can also compile straight onto the disk whenever memory is running a little tight. This will certainly be slower than compiling into memory, but you'll still be able to compile most programs in a matter of seconds. CHAPTER 7: COMPILING FROM THE CLI If you're a CLI enthusiast, you can also access the compiler directly from the command line. The ACMP utility is a complete standalone version of the compiler which provides you with total control over the compilation process. Since ACMP is only about 27k long, it can be copied straight into your C directory. Hard disk users just need to copy the file across from the installation program. Floppy disk users just need to copy the file across from the compiler disk. You'll now be able to compile your programs instantly from anywhere in your system. Don't delete the original version of ACMP from the AMOS_System folder though. You'll need it whenever you call the compiler from within AMOS Basic. As a default, the compiler will expect to find a series of libraries in the :AMOS_System/folder in the root directory of your current disk. This folder should also contain a copy of the current Compiler_Configuration file. If these files are stored on another drive, you'll need to enter their pathnames explicitly from the command line using the options: -F and -C. The syntax of the ACMP command is: ACMP [source.AMOS] [,OPTIONS] where source.AMOS is the program to be compiled. If the source program is omitted, a default filename will be automatically read from the Compiler_Configuration file. If you are continually compiling the same program, you can save some time by editing the Compiler_Configuration file and replacing the default with the current program name. You will now be able to compile your program with a simple: 1>ACMP Also note that if the filename includes embedded spaces, the whole pathname should be enclosed between quotes. For example: ACMP "test program.AMOS" compiles 'test program.AMOS. COMPILER OPTIONS The AMOS compiler supports a wide range of powerful options which can be entered straight from the command line. Each option is specified by a dash - followed by a single letter in upper or lower case. Any additional information should be placed immediately after an initial letter. Spaces are not allowed, as they are needed to separate the various compiler options. Also note that the quote system mentioned previously can only be used inside a path or filename specification. CHOOSING THE DESTINATION FILE -object_file (Object) object_file is the name of the new file which will be used to hold the compiled program. If it's omitted, the compiler will automatically generate the destination filename by removing the ".AMOS" suffix from the original name. Note: The new filename should be placed immediately after the -O. So don't include a space after the -O. The object file doesn't have to be on the current drive of course. It can be stored on any disk you like. If you've only access to a single drive, you can place your object file on a separate disk. Providing you are compiling completely in memory you'll only have to swap the disk twice. Obviously, you should NEVER use this feature when you are compiling to the disk, as you could waste hours swapping between the various disks. Examples: 1>ACMP prog.AMOS -Oprog compiles the program prog.AMOS and places the completed program into the file prog. The new program can now be executed from the CLI by simply typing: 1>prog MEMORY CONSERVATION -D00/-DO1/-D10/-D11 (Disk/Memory) These options allow you to choose where the compilation process takes place. The first digits sets the position of the source of your AMOS program, and the second selects the destination. Each digit can take one of only two values: 0 = Compile into RAM (Equivalent to the RAM icon from the accessory) 1 = Compile to disk (Same as the Disk icon) Here is a list of the four possible alternatives: D00 (Source=RAM Dest=RAM) The compilation process is performed entirely in memory. This option is very fast, but it also requires large amounts of memory. D01 (Source=RAM Dest=DISK) This setting loads the entire source program into memory, and then copies the destination program onto the disk as it's being compiled. Although there's a considerable saving in memory, it's much slower than the previous option. D10 (Source=DISK Dest=RAM) Saves memory by reading each line of your AMOS Basic program from the disk as and when it's needed. The compiled program is created in RAM for maximum speed. Although the compilation process is faster than the D01 option, the memory savings are significantly less. D11 (Source=DISK Dest=DISK) This option should only be used when you are desperately short of memory as it's fairly slow. It does however, consume just 70k of storage space, whatever the size of your program! Examples: 1>ACMP prog.AMOS -D11 compiles the new program onto the disk and places it into a file called prog. 1>ACMP prog.AMOS -Oprog -D01 Loads prog.AMOS into memory and compiles it straight on the disk file prog. SETTING THE TYPE OF THE PROGRAM -T0/-T1/-T2/-T3 (-Type) These options allow you to choose the type of the compiled program. There are four possibilities: -T0 This option will automatically produce an icon along with your compiled program. It's now possible to execute the compiled program directly from the Workbench by clicking on the new icon. -T1 Generates a program in standard CLI format. The compiled program can be called straight from the command line by typing it's name. You can also include parameters in the command line as well. These can be read from your command line as well. These can be read from your compiled program using the special COMMAND LINE$ function. Note that apart from the icon, there's absolutely no difference between the CLI or the Workbench versions of your program. So you can happily execute your Workbench programs from the CLI. -T2 Creates a CLI program which will automatically run in the background using multi-tasking. You can also generate the same effect by executing a -T0 or -T1 program with the AmigaDos RUN command. WARNING! On entry to your program, the current directory will be automatically switched to "SYS:". As normal, you can change this directory by calling the simple DIR$ command at the start of your program. For example: DIR$="Dh0:AMOS_Games/" -T3 Compiles a .AMOS program which can only be run from the AMOS editor. Any attempt to execute this program from the Workbench or CLI will be doomed to failure. SETTING THE DEFAULT SCREEN -S0 -S1 (-Screen) As a default, your compiled program will automatically create a standard AMOS screen for your graphics. This screen will be displayed on your monitor during your program's initialisation phase, often leading to an unwanted flash effect. The -S0 option deactivates this feature, and allows you start your program with a completely blank screen. WARNING! Don't forget to open a new screen BEFORE using any of the text or graphic commands, otherwise your program will immediately stop with a 'Screen not opened error'. -S1 restores the screen system to normal. A default AMOS screen will now be displayed whenever your program is executed. -W0/-W1 (Workbench) This option prevents AMOS from erasing the current Workbench or CLI screen when your compiled program is executed. You can now create your screen invisibly, without affecting the existing display in the slightest. When your screen is ready for display, you can now switch it neatly into place with the AMOS TO FRONT command. Here's an example: Rem Compile with -S0 and -W1 options set Rem e.g. acmp view.amos -S0 -W1 Rem Turn off screen updates Rem Open a new screen Screen Open 0,320,250,64,Lowres Rem Draw a simple screen For C=0 To 100 Ink Rnd(64): X1=Rnd(320): Y1=Rnd(200): Y2=Rnd(200) Bar Min(X1,X2),Min(Y1,Y2) To Max(X1,X2),Max(Y1,Y2) Next C Rem Flick display into place Amos to Front Walt Key -W1 suppresses the display of the current AMOS screens, and leaves the old CLI or Workbench screens intact. The effect is very similar to the AMOS TO BACK command from within AMOS Basic. But the transition between the two screens is noticably smoother! Expert users can exploit this feature to create standard CLI utility programs, although you'll have to write your own routines to output text to the CLI window. -W0 (the default) turns off the existing display before your program is run. When you return to the Workbench or CLI, the contents of the screen window will be completely redrawn. COMPILING LARGE PROGRAMS -L (Use Long jumps rather than branches) The -L option is only required when you are compiling really large programs. In these circumstances, the size of a program structure such as WHILE..WEND or IF..ELSE..ENDIF can exceed 32k. So the compiler will be forced to use a JMP instead of the normal BRA instruction. The compiler will now generate a 'Program Structure too long error', and you'll need to recompile your program with the -L directive. For example: 1>ACMP LARGE_PROGRAM.AMOS -L CHOOSING THE DEFAULT OPTIONS -Cconfiguration_file (Config) -C defines the name and location of the configuration file which will be used to hold the compiler's default settings. This file MUST be available when the compiler is executed, otherwise the compilation will be aborted. The default pathname is: AMOS_SYSTEM/Compiler_Configuration POSITIONING THE COMPILER LIBRARIES -Fpathname (Tell the compiler the location of the AMOS_SYSTEM folder) The -F option allows you to specify the full pathname of the AMOS_SYSTEM folder. In order to work, the compiler requires a number of library files to be available in the AMOS_SYSTEM folder. These contain the machine code versions of each AMOS instruction. Normally, the AMOS_SYSTEM folder will be found in the root directory of the current disk. You can however, place it anywhere you like: 'pathname' is a standard Amigados file spec ending a ":" or "/" character. The compiler takes ALL file names found in the configuration file, and replaces the original pathname with the new one. One possibility is to copy the entire folder into a RAM disk. This consumes a whopping 145k of memory, but results in blindingly fast compilation. Here's the procedure: First copy the folder to the RAM disk with: 1>Copy Df0:AMOS_System/To RAM:AMOS_System You can now compile your program with the -F option like so: 1>ACMP example.AMOS -CRAM:AMOS_ System/Compiler_Configuration - FRAM:AMOS_System/ Although this looks very complex, it would be easy enough to write a script file containing all the relevant commands. You could then call from the CLI using EXECUTE. For example: 1>EXECUTE RCMP example.amos ERROR HANDLING -E0 -E1 (-Errors) As a default, error messages are NOT copied into the compiled program. So if a problem occurs, or you press Control-C, the program will jump straight back to the Workbench, CLI or AMOS Editor, as appropriate. The -E1 option includes the standard AMOS error messages along with your compiled program. If your program aborts with an error, the relevant message will now be displayed on the screen. Since the program is in pure machine code, it is impossible to report the precise line number at which the problem occured. In order to find the position of the error, you'll therefore need to test the interpreted version of your program from AMOS Basic. Note: The compiler makes use of two DIFFERENT .Env files in the AMOS_SYSTEM folder: -E0 uses the RAMOS1_3.ENV file without error messages -E1 takes the environment from AMOS1_3_PAL.ENV / AMOS 1_3_NTSC.ENV BE CAREFUL! If you change the settings in one of the .ENV files, you MUST also make exactly the same changes in all the other versions! SUPPRESSING THE COMPILER MESSAGES -Q (-Quiet) This option will prevent all messages during the compilation process, except any error reports. COMPILING FROM DIRECT MODE You can also compile your programs from AMOS Direct mode using exactly the same system. This can be achieved with the aptly named COMPILE instruction: COMPILE command_string$ 'command_string$' specifies the name of the AMOS program to be compiled, and can include any of the options from the previous CLI section. Occasionally this feature can be very useful, especially if you are running short of memory. You can now save a great deal of space by removing the compiler accessory and compiling the program from Direct mode. Before using this command, it's a good idea to close the default screen with Screen Close 0. This will force the compiler messages to be displayed in the direct mode window, saving 32k of memory! Here are a couple of examples: AMOS>compile "prog.AMOS -D01 -T3" compiles a file called 'prog' from the current disk in .AMOS format. This file can then be loaded into AMOS Basic and run straight from the editor. AMOS>compile "prog.AMOS -Oprog -T0" This line compiles the program 'prog' and places the new machine code version into the file 'prog'. The T0 option automatically creates an appropriate icon for your program. If you select this icon from the Workbench, the program will be executed immediately. See the chapter on THE COMPILER EXTENSION for more details. CHAPTER 8: THE COMPILER ACCESSORY COMPILER.AMOS is a standard AMOS program which can be loaded directly from the AMOS interpreter. Usually, you'll want to enter the compiler as an accessory with the LOAD OTHER command (Shift F6). You'll now be able to access the compiler at a moments notice using RUN OTHER (F6). Note that the compiler only works with disk files. So you'll need to save your program onto the disk before compiling it. On entry to the accessory, you are immediately presented with the following control panel. +-------------------------------------+ | A M O S C O M P I L E R | +-------------------------------------+ | +-------+ +-------+ +-------+ | | | R A M | -> | DISK | : | W B | | | +-------+ +-------+ +-------+ | | +-----------------------------+ | | | COMPILE >>>>>>>>>>>>>>>>>>>> > | | +-----------------------------+ | | +---------+ +------+ +-------+ | | | E X I T | | ? | | >---< | | | +---------+ +------+ +-------+ | +-------------------------------------+ Along the top you can see three large icons. These activate the compiler's memory conservation features and allow you to set the type of the compiled program. You may have a slightly different icon selection to that shown here. It all depends on the configuration you chose when installing the compiler. SOURCE DESTINATION TYPE | | | +-------+ +-------+ +-------+ | R A M | -> | DISK | : | W B | +-------+ +-------+ +-------+ Each option can be toggled between the several alternatives. They can be selected by simply moving the mouse pointer over the appropriate icon and clicking once on the left mouse button. A new icon will now flip neatly into place to reflect the current setting. SOURCE The Source icon determines whether your program should be compiled either from memory or directly from the current disk. There are two possibilities: +-------+ The Ram option loads the entire program into memory before | R A M | it's compile, resulting in the fastest possible compilation. +-------+ It does however consume a fair amount of memory, so if your program is large in size, or you are using an unexpanded machine, you may be forced to select the Disk option instead. This can be accessed by clicking on the Ram icon. +-------+ The Disk feature conserves memory by reading each line of | DISK | your program straight from the disk as and when it's +-------+ required. Although this system is considerably slower than compiling from memory, it does avoid the need to load the whole program into RAM. If you think you're running short of memory, you can get an instant read-out of the amount available RAM by holding down the right mouse button. DESTINATION The Destination icon controls the way the compiled program will be created on the disk. As with the Source icon, there are two possible settings. +-------+ This generates the compiled program into a separate memory | R A M | area. When the compilation is complete, the finished program +-------+ is saved directly into your new file. Compiling to RAM is extremely fast, but it does require a reasonable amount of memory in order to work. This won't be a problem if you've a megabyte or more of RAM, but if you're using an unexpanded A500, you could easily get a dreadful 'Out of memory error'. Don't panic though! We've thoughtfully provided you with powerful memory conservation system which can be selected by just clicking on the Destination icon. The RAM chip will be replaced by a picture of a disk. +-------+ The Disk option compiles your program straight onto the disk, | DISK | one piece at a time. This uses a maximum of 70k of memory, +-------+ irrespective of the size of your program. You can therefore compile massive AMOS programs on even the smallest machine. The only limitation is the amount of space on your current disk! One obvious side effect of this system is that the compilation process is fairly slow, especially if you don't have access to a hard disk. In extreme cases, it could take several minutes to generate the compiled version of your program. TYPE This option has three possible states which can be toggled by clicking once on the left mouse button. +-------+ Creates a program which can be run straight from the Amiga | W B | Workbench by simply clicking on its icon. An appropriate +-------+ icon will automatically be saved in a .info file with your compiled program. This icon can be redrawn using the IconEd utility found in the Tools folder of your Workbench disk. +-------+ The CLI option compiles your programs into a form which can | C L I | be executed immediately from the Amiga CLI or SHELL. The +-------+ program can be run from the command line by typing its name. For example: 1>test runs a program called Test. Note that apart from the .info file, CLI programs are identical to the Workbench versions. +-------+ The .AMOS option generates a program which can only be | AMOS | accessed from inside AMOS Basic, just like the interpreted +-------+ versions. Since the entire AMOS system is already available at run-time, these programs are around 40k smaller than their Workbench or CLI equivalents. You can therefore execute quite large .AMOS programs even on a standard A500. Compiled programs are stored in the form of a locked procedure. This procedure is loaded into the edit buffer and can be copied between programs using the Block command. The only difference between the compiled program and a normal AMOS procedure is you obviously can't unfold it from the editor. A typical program listing would be: Rem Sets the size of the variable space. Standard AMOS instruction. Set Buffer 8:rem sets the current amount of variable space Rem call compiled program Proc_COMPILED Rem locked procedure Procedure_COMPILED +--------+ Once you've set up the various compiler options, you can | COMPILE > start the compilation process by simply clicking on the +--------+ Compile button. You'll now be prompted for the name of the AMOS program to be compiled. This is entered using a standard AMOS file selector. The final step is to choose the filename which will be used to hold the compiled program. Clicking on the OK button will automatically choose a default. This varies depending on the type of your program. "AMOS" programs have C added to the original filename just before the extension. So "Test.AMOS" becomes "Test_C.AMOS". CLI or Workbench programs have the ".AMOS" suffix removed. Therefore "Test.AMOS" would be compiled as "Test". After the source and destination filenames have been entered, compilation will commence. If you make a mistake, the compilation can be aborted by simply pressing Control-C. An indication of the current progress can be seen from the arrow icons to the right. A new arrow will be automatically highlighted after each stage of the compilation. When the last arrow has been reached, the compiler has completed its work, and your program is ready for use. The accessory will now list the size of the new program in a small information line below the control panel. Click on the left mouse button to continue. +-------+ | EXIT | Quits from the compiler accessory and returns you either the +-------+ the Workbench or the AMOS Editor as appropriate. +-------+ | ? | Displays the program credits. This one's very important! +-------+ +-------+ The Spanner icon forms the gateway to a separate Options menu | >---< | which enables you to fine tune the compiler to your +-------+ particular needs. Whenever the compiler is run, the current setting are automatically read from the Compiler_Congiguration file in the AMOS_SYSTEM folder. These settings can be changed at any time by simply clicking on the relevant icon from the Options menu. COMPILER PROGRAM SETUP +--------------------------------------------------------------------+ | +--------------------------+ | | | Compiler program setup | | | +--------------------------+ | | | | - Include error messages? No | | | | - Create default screen? Yes | | | | - Send AMOS to BACK upon booting? No | | | | - CLI programs to run in the background? No | | | | - Long forward jumps (option -L for VERY long programs)? No | | | +--------------------------------------------------------------------+ INCLUDE ERROR MESSAGES? This feature allows you to include the standard AMOS error messages along with your compiled program. Depending on your selection, your program will use one of two possible environment files. 'Yes' loads the environment from the normal AMOS configuration file along with the usual error messages. Whenever an error occurs in one of your compiled programs, an appropriate message will be displayed on the screen. Note that the environment will be taken from the AMOS1_3_PAL.ENV file in the AMOS_System folder (or AMOS1_3_NTSC.ENV for NTSC users). 'No' turns off the error messages and reads the environment from RAMOS1_3.ENV instead. If a problem occurs in your program, it will now abort immediately and return straight to the Workbench or CLI. WARNING! It's important to ensure that both configuration files contain exactly the same screen settings, otherwise your program display could change unpredictably when you remove the error messages. CREATE DEFAULT SCREEN Normally, a standard AMOS screen will be created automatically for your compiled program. 'No' starts your program with a totally clean display. It's equivalent to using the -S0 option from the command line. Note your program MUST open a new before performing ANY output (print, fade, bob and so on). If you forget about this, the program will abort immediately with a 'Screen not opened error'. 'Yes' spontaneously generates a default screen for the compiled program whenever it is run. SEND AMOS TO BACK UPON BOOTING? 'Yes' completely hides your current display, just as if you had included an AMOS TO BACK instruction at the start of your program. The screen can be reactivated at any time with the AMOS TO FRONT command. CLI PROGRAMS TO RUN IN THE BACKGROUND? This option is only relevant if you are compiling your program as type CLI. The 'Yes' button forces the compiled program to detatch itself from the CLI and run as a separate process under the Amiga's multi-tasking system. The same effect can be achieved by executing a normal CLI program with the AmigaDos Run command. LONG FORWARD JUMPS (OPTION -L FOR VERY LONG PROGRAMS)? Forces the compiler to use JMP instructions rather than BRAnch commands in the compiled program. It's needed to allow program structures such as IF..ELSE..ENDIF and WHILE..WEND to work in ranges over 32k. Toggle the 'Yes' option if you get a 'Program structure too long, compile with -L option' message during compilation. When you re-compile, everything will be fine. COMPILER SETUP +--------------------------------------------------------------------+ | +--------------------------+ | | | Compiler program setup | | | +--------------------------+ | | | | - Copy all libraries onto RAM-disk? No | | | | - Leave libraries on RAM-disk upon exiting? No | | | | - Keep compiler program "ACmp" in memory upon exiting? No | | | | - Squash compiled program? No | | | +--------------------------------------------------------------------+ COPY ALL LIBRARIES ONTO RAM-DISK? If you've got an expanded machine, you can save a great deal of time by copying all the compiler libraries onto a super-fast RAM disk. The whole process is completely automatic. Note: This feature can only be used with at least one meg of memory since the libraries consume around 145k of RAM. 'Yes' instructs the compiler accessory to copy the compiler libraries straight into the 'AMOS_Compiler_Temp' folder on the RAM disk. If the RAM disk is not installed, the option will be completely ignored. 'No' deactivates the RAM disk, saving 145k of valuable memory. LEAVE LIBRARIES ON RAM DISK UPON EXITING? Stores the compiler libraries permanantly on the RAM disk. 'Yes' is a VERY powerful option for users who have one meg of memory and just a single disk. Once the libraries have been installed, the original compiler disk can be safely removed. You can now place a new disk containing your programs and data into the internal drive and compile away. WARNING! This system will only work if you've also elected to keep the compiler in memory (see next option). Otherwise, whenever you run the accessory, you'll be asked to insert the compiler disk into the drive. After the program has loaded however, you can replace the compiler disk with your own program disk as before. If you are compiling a Workbench program, the compiler will also need to open the icon.library from the LIBS: folder. It will therefore ask you to insert your boot disk if you have removed it. If this is inconvenient, simply set the program type to CLI or AMOS. 'No' forces the accessory to delete the entire contents of the RAM disk when you return to the Editor. This frees about 145k of memory for use with your programs. The next time you load the accessory the libraries will automatically be copied onto the RAM disk. KEEP ACMP IN MEMORY UPON EXITING? This option is related to the previous one, and to the compiler extensions commands. 'No' tells the compiler accessory to perform a COMP DEL instruction before returning to the Editor. So the next time you run the compiler, it will ask you to insert the original compiler disk. 'Yes' keeps the compiler in memory until you quit AMOS Basic. This consumes approximately 27k of RAM. SQUASH COMPILED PROGRAMS? Selecting 'Yes' will compress your new program and save it straight onto the disk. The squashed program be will be automatically decompacted whenever it's loaded from the CLI or Workbench. You can abort the compaction process at any time, by simply pressing Control-C from the keyboard. You'll now be returned straight to the compiler accessory. If there's not enough space on the disk, the squashing will also be terminated in exactly the same way. Note: This option has no effect on programs compiled as type AMOS. +-------------------------------------------------------------------+ | +-------------------------- +-----+ | | Save this configuration | EXIT| | +-------------------------- +-----+ +-------------------------------------------------------------------+ SAVE THIS CONFIGURATION? Saves the current Compiler_Configuration onto your working copy of the compiler disk. If the compiler disk is not available, you'll be asked to replace it in one of the drives. This option also saves the present status of the Source, Destination and Type buttons on the control panel. So you can easily tailor the initial compiler settings to precisely your own requirements. EXIT Returns to the main compiler menu. CHAPTER 9: COMPILER EXTENSION COMMANDS The AMOS compiler extension adds several new instructions to the existing AMOS Basic system. COMPILE (Compile a program from AMOS Basic.) COMPILE command_string$ As its name suggests, this command enables you to call up the compiler straight from your AMOS Basic programs. It was originally designed to allow the creation of the AMOS compiler accessory, but it can also be used from Direct mode if required. If the compiler has not been previously loaded into memory, the extension will immediately try to install it from the default path (usually :AMOS_System/). Also note that you'll need to define an 80 column hires screen to display the various error messages. For example: Screen Open 0,640,200,16,hires If you're calling the COMPILE instruction from Direct mode, you can also use the Direct mode screen for these messages. Simply close screen 0 with: AMOS>Screen Close 0 'command_string$' contains the name of the program to be compiled, along with an optional list of compiler directives. The format is identical to that used by the ACMP utility. Here's a quick rundown of the more useful options: command_string$="program.amos [-Oobjectname][-Dnn][-Tn][-Q]" 'program.amos' is the name of an AMOS program to be compiled. '-Oobjectname' specifies the filename to be used as the destination. The default is simply the original name of your program without the ".AMOS" extension. If your filename includes spaces, you'll need to surround it with a pair of single quotes. For example: compile "'test.amos'-D11" '-Dnn' activates the compiler's memory conservation features: -D00 = From RAM to RAM (This is the default) -D01 = From RAM to disk -D10 = From disk to RAM -D11 = From disk to disk '-T' chooses the type of your compiled program. -T0 = Workbench (default) -T1 = CLI -T2 = CLI with multi-tasking -T3 = .AMOS '-Q' suppresses all system messages generated by the compiler, except errors. Examples: AMOS>compile"prog.amos" Compiles 'prog.AMOS' and stores the new version in the file prog. This file can now be executed from either the CLI or Workbench as required. AMOS>compile"prog.AMOS -T3" Compiles your program in .AMOS using the memory to memory option. After the compilation is complete, you can load the new program straight from the editor. AMOS>compile"prog.AMOS -Oprog -D11" Creates a compiled program called 'prog' along with the appropriate Workbench icon. The -D11 option activates the memory conservation system, and uses the absolute minimum of RAM. If you are compiling onto floppy disk, you may have to wait a couple of minutes for the process to complete. See COMPILING FROM THE CLI for full details of the available compiler options. COMPTEST (Carry out compiler tests) COMPTEST COMPTEST ON COMPTEST OFF AMOS Basic regularly carries out the following tests during the execution of your programs: o Sprites and Bobs are redrawn at their new positions. o Menus are checked for the presence of the mouse. o The Control-C keys are tested. COMPTEST ON Checks are only carried out before jump instructions such as GOTO or WHILE, and time consuming commands like PRINT or WAIT. This is the standard system used by the AMOS Basic interpreter. COMPTEST OFF The COMPTEST OFF command stops the testing completely, and improves the speed of your program by up to 10%. this allows you to optimise time critical sections of your compiled program for the maximum possible speed. It's especially useful in programs such as fractal generators or 3D routines, which need to perform vast numbers of calculations in a relatively short space of time. WARNING! One side effect of COMPTEST OFF, is that the Control-C feature is completely disabled. So that if a problem occurs in one of your programs, you'll be unable to get the AMOS Basic editor without completely rebooting, it's therefore vital to SAVE your program onto the disk before using this feature, as otherwise you could lose hours of valuable work! COMPTEST Performs a single test at a specific point in your program. This command would normally be used after a COMPTEST OFF to provide you with total control over the entire testing process. COMP LOAD (Load the main compiler software) COMP LOAD ["path"] In order to conserve memory, the compiler is only loaded from the disk as and when you need it. Amazingly enough, the actual compiler extension consumes less than 2k of RAM, including the squasher routines! This leaves you with plenty of space for even the largest interpreted programs. COMP LOAD loads the full compiler utility into memory, consuming around 27k of RAM in the process. As a default, the compiler will be taken from the ACMP file from within the AMOS_System folder of your current boot disk. A 'file not found' message will be returned if it's not available. The optional pathname allows you to load the compiler from anywhere on you present system. This feature is mainly intended for owners of hard disks who wish to keep the compiler in a seperate folder such as C. Examples: AMOS>COMP LOAD Loads the compiler into memory from the AMOS_SYSTEM folder. AMOS>COMP LOAD "Dh0:C/ACMP" Loads the compiler from the C directory of your hard disk. The compiler remains in memory until you leave the AMOS Basic or call the COMP DEL instruction. COMP DEL (Restores the memory used by compiler) COMP DEL Removes the compiler from memory and frees about 27k of RAM for use by your AMOS Basic programs. =COMP HERE (Returns compiler status) f=COMP HERE COMP HERE returns a value of TRUE(-1) if the compiler is already installed in memory, or FALSE(0) if it is not available. =COMP ERR$ (Return last error message) m$=COMP ERR$ This function returns the LAST error message generated by the compiler in the string M$. If there was no previous error, M$ will be loaded with an empty string "". =COMP SIZE (Return compiled program size) I=COMP SIZE The effect of the COMP SIZE varies depending on when it is called. It holds the size of the last successful compiled program. If it's read immediately after a compilation, it will contain the length of the program in bytes. The next time it's called, it will return the number of instructions. Any further accesses returns a value of zero. RUN (Run a compiled program) RUN "program name" Actually, this isn't a new command at all! It's just an extended version of the original AMOS Basic RUN command. But it's important to emphasise that compiled programs can be chained together, just like interpreted versions. You can therefore easily split your program into several parts which can be loaded straight from the disk as and when they are required. This technique is widely used in commercial games. Each level in the game is now assigned to a seperate program on the disk and loaded separately, saving vast amounts of valuable memory. RUN can be freely used in any of your compiled programs. The only limitation, is that interpreted or AMOS type programs can only be executed from the AMOS System. So you can't just run an interpreted program from the CLI or Workbench and expect it to work. Example: AMOS>Run"3d_demo_C.AMOS" =COMMAND LINE$= (Read/Set command line parameters) C$=COMMAND LINE$ COMMAND LINE$ is a new reserved variable which allows you to access the contents of the CLI command line directly from your compiled program. =COMMAND LINE$ returns a string containing the entire list of parameters which have been entered in the command line. If they've not been defined, you'll get an empty string ("") instead. NOTE: You are recommended to read the command line as soon as possible after the start of your program, as it's held in a buffer used by the AMOS Basic graphic instructions. After the command line has been read, any further calls will just return "". Example: 1> test one two three Runs the compiled program 'Test' and loads COMMAND LINE$ with the string 'one two three'. COMMAND LINE$="strings" This loads the command line with up to 256 characters of your own data. It's normally used just before the RUN command to preserve vital information between two chained programs. (compiled or interpreted). Example: Command Line$=Str$(SCORE) Run "Level2.AMOS" Saves the score into the command line and then executes a new program called 'Level2.AMOS' straight from the disk. You could now read the score at the start of Level2.AMOS program using a line like this: SCORE=Val(Command Line$) =SQUASH (Compact an area of memory) L=SQUASH(address,Length,Flag,Ahead,Colour) Compresses an area of memory into a fraction of its normal size. The squashing process can be aborted at any time by pressing Control-C. 'Address' holds the address in memory of the data to be squashed. Usually, the data will be taken from the previously reserved AMOS memory bank, but you can also compress other memory areas with this system as well. But NEVER attempt to squash a sprite or icon bank. This type of data is not stored in one continuous memory block. You can however, freely squash all other banks including those containing samples of menus. 'Length' specifies the number of bytes of data to be compacted. WARNING! The squasher will automatically overwrite your existing data with the new version. 'Flag' toggles the squasher between two modes: Flag=0: Sets SLOW MODE. This is mainly intended for users of unexpanded machines and reserves the absolute minimum amount of space. As the name suggests, the compression will take a while to complete. Flag<>0: Activates FAST MODE and compacts the data into a seperate memory area for the maximum possible speed. In order to use this feature, you'll need enough RAM to hold a memory area twice as large as the zone to be squashed. If you run out of space, AMOS will automatically flip back to SLOW mode. If SLOW mode has been set, 'Ahead' specifies how far (in bytes) the squasher will search ahead during the compaction process. The higher the figure, the greater the compaction and the slower the execution speed. The minimum is 256 (fast but efficient), and the maximum is 4096 (very slow). A reasonable value to use is about 1024. 'Colour' is the number of a colour (0-31) to be flashed on the screen while the data is being squashed. After your data has been compacted, the squasher will return one of the following values: L>0: This indicates that the squash has been successful and holds new length of the compressed data. L=0: The squash was terminated with Control-C. L<0: The compression has been aborted because the squashed length turns out to be longer than the original. This is very rare with most data, but samples will probably always return such values as they are hard to squash. =UNSQUASH (Unpack a squashed memory area) L=UNSQUASH(Address,Length) This function restores a block of data which has been compressed with the SQUASH instruction. 'Address' holds the address of the first byte of the squashed data. 'Length' specifies the number of bytes to be decompressed. This should be length of the packed data as returned by the previous SQUASH command. Beware! Unsquash completely overwrites the current data. You MUST therefore always reserve a bank of the original (unsquashed) length to hold the new data. You can now BLOAD the packed data at the beginning of this bank, and call the UNSQUASH function. Example: Rem Rem Squasher demo Rem This kind of picture is very difficult for squashers! Rem Screen OPen 0,640,200,2,Hires Colour 1,$FFF For N=0 To 80 Circle Rnd(639),Rnd(199),Rnd(50)+1 Next N Rem Screen Open 1,640,3*8,4,Hires Curs Off Screen Display 1,,220,,:Wait Vbl Rem Do Bell:Centre At(,1)+"Press any key to Squash" Wait Key Rem Screen 0:Screen To Front 0:Wait Vbl Timer=0 S=Squash(Logbase(0),16000,-1,1024,17) Rem Screen 1:Screen To Front 1:Wait vbl Cls Centre At(,1)+"Picture squashed in"+Str$(Timer/50)+"seconds" Centre At(,1)+"Original size: 16000 bytes, squashed size:"+Str$(S) Centre At(,2)+"Press any key to unsquash the picture" Wait Key Rem Screen 0:Screen To Front:Wait Vbl L=Unsquash(Logbase(0),S) Rem Screen 1:Screen To Front 1:Wait Vbl Cls Centre At(,0)+"Picture restored!" Loop CHAPTER 10: COMPILER VERSUS INTERPRETERS As you probably know, your Commodore Amiga is only capable of running programs in in internal language known as Machine Code. Each machine code is represented by a specific combination of one and zeroes (binary) inside the computer. If we had to write all our programs in binary, we'd obviously be faced with an impossible task. We've therefore invented a range of other languages such as Basic, C, and Pascal to make life easier for ourselves. Before these high-level languages can be run on your computer, they first need to translated into machine code. Over the years, a number of approaches have evolved. The original AMOS Basic system made use of a technique called interpretation. An interpreter takes each Basic instruction, one at a time, and locates the equivalent piece of machine code in a special dictionary. Once its found the command in memory, AMOS then executes the routine using the machine code version of the standard GOSUB. The major advantages of the interpretation process, is that it allows your program to be stored as a simple list of Basic instructions. this means that your AMOS programs can be edited directly from the editor, and then run immediately when required. It's therefore possible for you to develop large and powerful Basic programs with the absolute minimum of effort. Despite its undoubted friendliness though, interpretation isn't particularly efficient. Every time AMOS encounters one of your instructions, it has to jump immediately to the relevant bit of machine code. Although this process is extremely fast, It's certainly not instantaneous. So if your program contains a lot of small instructions, it could be spending more time on the interpretation procedure than in running your actual program. The worst offenders are programs which include a large number of complex calculations, becuase each individual arithmatic operation needs to be interpreted separately by the computer. The classic way of avoiding these problems is to use a compiler. Instead of interpreting each instruction individually, a compiler takes the entire program and translates it directly into a separate machine code file on the disk. After the program has been converted, it can then be run straight from the Workbench or CLI. This makes it possible to freely distribute your programs to any Amiga user, regardless of whether thay have a copy of AMOS Basic. All you need on the disk is the compiled program and a couple of standard Amiga libraries. That's it! What's more, since the interpretation process is now sidestepped, there's also a considerable speed improvement. Obviously this varies dramatically depending on the type of program you are compiling. Some programs are barely affected at all, whereas others execute an incredible four times faster. The biggest improvements are in programs which execute a lot of calculations, such as simulations, 3D routines or business utilities. The only serious drawback is that compiled programs tend to be rather larger than the interpreted versions. In practise, this isn't much of a problem, since compiled programs are completely independant of the AMOS Basic system, and the final size includes everything needed to run the program on your Amiga. This contrasts markedly with interpreted programs, which can only be run from a separate interpreter such as AMOS Basic or RAMOS. Since RAMOS consumes a massive 80k or so of memory, the total size of your interpreted program often works out to be considerably larger than the compiled version. Here's a quick summary of the relative merits of compilers and interpreters: INTERPRETED PROGRAMS: o Are small, compact and very easy to debug. o Can be freely edited from AMOS Basic. o Require a seperate interpreter such as AMOS or RAMOS in order to run. o Are not very good at handling programs with lots of calculations. COMPILED PROGRAMS: o Are completely independant of the AMOS Basic system, and can be run directly from the Workbench or CLI. o Executes up to four times faster than the interpreted versions. o Cannot be examined or modified without the original interpreted program. o Are significantly larger than interpreted programs. CHAPTER 11: RUNNING A COMPILED PROGRAM There are three possibilities: WORKBENCH PROGRAMS If you compiled your programs using the WB option, you will be able to execute it straight from the Workbench by simply clicking on the appropriate icon with the mouse. As the program is loading, the mouse pointer will flicker continuously. Don't worry if the process takes several seconds. AMOS is simply unsquashing the various system routines. WARNING! If you click on the icon twice, you could launch another copy of the same program! CLI PROGRAMS These programs are created when you select the CLI option from the compiler accessory. They can be executed from the CLI by just typing their name. For example: 1>demo This runs a program called demo from the current disk. If the program you wish to run is on another drive, you'll need to include the current pathname like so: 1>Df1:demo The Amiga treats CLI programs exactly like any other machine code program, so they can be called from within batch files or executed automatically on startup. See 'CREATING AN AUTOBOOT DISK' for more details. Normally, AMOS will generate a standard screen for your graphics. This can be suppressed with the -S0 option during compilation. You can also include parameters. These will be automatically loaded into the reserved variable COMMAND LINE$ when your program is initialised. For example: 1> demo test executes a compiled demo program called 'Test'. When the program begins the parameter test will be placed into the string COMMAND LINE$. AMOS RUNNABLE PROGRAMS These programs can be run directly from the AMOS Basic interpreter, and are usually around 40k smaller than the equivalent CLI or Workbench versions. If you've a megabyte or more of RAM, you'll often be able to hold both the interpreted and compiled versions of the program in memory. This will speed up your development process enormously. In order to make use of this feature, you first need to compile your programs in a special .AMOS format. This can be accomplished from the compiler accessory by setting the Type icon to AMOS. You can now load your compiled programs and run them straight from the editor. The editor window will contain the following lines: Set Buffer n:Rem where N is the current size of the variable area Proc_Complied Procedure_Compiled The procedure_COMPILED is locked and contains your compiled programs. Note that the above program definition is taken from a file called Header_AMOS.AMOS in the AMOS.System folder. You can edit this file to change the name of the compiled procedure to something more exiting. For example: Set Buffer 8 Proc Amosteriods Procedure Amosteriods WARNING! The procedure definition contained by the header holds a special instruction used to execute the compiled program. This should be left exactly as it stands. If you try to run the header program from the interpreter .AMOS will immediately crash! The compiled program is stored in the editor buffer, and is treated just like any normal AMOS program. All memory banks are in the standard format and can be loaded, saved or grabbed as required. You can even execute a compiled program as an accessory. As an example, try compiling the new sprite editor on the AMOS compiler disk. Not only is there a noticeable increase in the execution speed, but the testing process is instantaneous. EXITING FROM A COMPILED PROGRAM The compiled program will automatically return you to the calling environment after it has completed successfully. You can however, abort from the program at any time by holding down the Control and C keys. ERROR MESSAGES If you've compiled your program with the 'include error messages' or -E1 option from the command line, a standard AMOS error message will be displayed when something goes wrong. The format naturally depends on the environment you are using: WORKBENCH The message will be displayed in a small alert box. CLI The error will be returned in the form of a normal CLI message. AMOS The error will be indicated on the INFO line of the AMOS Editor. Note that the error messages are exactly the same as the interpreted versions, except that there are no line numbers. If you want to find the exact position at which the error ocurred, you'll need to test the original interpreted program from within AMOS Basic. If you've omitted the error messages, your program will simply quit and return in the event of an error. CHAPTER 12: CREATING AN AUTOBOOT DISK The best way of distributing your work to your friends is to create a boot disk for your compiled AMOS program. This will allow people to execute your programs by simply inserting your disk into the internal drive and booting up their Amiga. A good example of this technique is the Welcome program used for updating and installing. The easiest method of generating a boot disk is to CHEAT! o Make a copy of the original AMOS compiler disk and delete everything from the copy EXCEPT the following files and directories: C: DEVS: L: LIBS: S: Disk.info Obviously, you should not use the original compiler disk for this purpose! o Compile your program onto this disk in the CLI or Workbench format. o Load up AMOS Basic V1.3 o Run the AUTOBOOT.AMOS program from the Updater disk. o Simply place the new boot disk into the internal drive, and choose your compiled program from the file-selector. A new startup-sequence file will be automatically created for you on the disk. Your program will then be loaded immediately whenever the new disk is booted on your Amiga. CHAPTER 13: TECHNICAL DETAILS In this section we'll be providing a fascinating glimpse inside the AMOS Basic compiler. IMPROVED GARBAGE COLLECTION The problem of garbage collection arises because of the way AMOS Basic handles strings. Take the following program: Rem Garbage creator! Input A$:Rem input a string A$=A$+A$:Rem Add a second copy of the string onto the end B$=A$-"":Rem Remove all the spaces Do C$=Left$(A$,3) Print A$,B$,C$ Loop The above program may look pretty simple, but underlying all this casual string manipulation, AMOS Basic is performing a frantic amount of activity. Whenever you assign some text to a string, the existing contents need to be discarded, and space has to allocated for the new data. Memory is also needed to hold the immediate results generated by string operations such as Left$, or "-". One unfortunate side effect of this process is that the variable buffer quickly fills up with useless string data. AMOS is then forced to claw back the unused space by completely reorganising the entire variable buffer. In extreme cases, this garbage collection can take several seconds to complete, leading to sudden and inexplicable delays in your programs. Luckily, there's a solution. AMOS 1.3 now includes a brand new garbage collector which executes an incredible 100 times faster than the original version. The UltraFast Garbage Collection (TM) will only work if there's enough continuous RAM to hold a complete copy of the variable buffer in memory. If this memory is not available, AMOS will automatically revert to the Old Garbage Collection (TM) system. Here's a program which demonstrates the speed gain: Rem Rem Garbage collection demo Rem Set Buffer 128 NN=3000 Dim A$(NN),B$(NN),C$(NN) For N=0 To NN Home:Print N AA$=Str$(N)+Str$(Rnd(Rnd(100))) A$(N)=AA$+"-" B$(N)=A$(N)+AA$ C$(N)=B$-AA$ Next N Rem Timer=0:Print Free:Print Timer INSIDE THE AMOS COMPILER MEMORY MANAGEMENT The compiler only reserves precisely the memory it needs. If there's not enough memory, you'll get an 'Out of Memory error'. DECODING THE COMMAND LINE 1. The command line is read and checked for all the allowable compiler options. If an error is found, the compiler ignores the remainder of the text and jumps immediately to stage 2. 2. The default compiler options are now loaded from the configuration file. Normally the options will be taken straight from the COMPILER_CONFIGURATION file in the :AMOS_SYSTEM folder, but this can be changed using the -C option from the command line. The config file also contains the entire list of error messages used by the compiler. These can be modified by simply editing the file with a standard ASCII text editor. 3. The default command line is loaded from the configuration file, and any options set. 4. The CLI command line is now checked yet again. So any options you select from the command line will override the defaults in the configuration file. 5. The source file is opened. If the SOURCE=RAM: option has been set, the file will be immediately loaded into memory. 6. Once the options have been set, the compiler reserves all the memory buffers it needs, and starts compiling your program. THE COMPILATION PROCESS REVEALED The AMOS compiler is a one-pass compiler. So it only needs to read the source code a single time to convert it into machine code. That's why it's so fast! The compiler works in the following way: o First, the program header is copied into the compiled program. This varies depending on the type of your program. (AMOS/CLI/WB) o The main program is converted into its machine code equivalent. o Any procedures in your program are compiled one after another. o The library routines are then copied into the compiled program, one at a time. The compiler will only copy the instructions which are actually needed by your program. So the size of a program depends on the number of different commands it uses. If you use all the AMOS instructions, the size of your program will reach RAMOS proportions. o The compiler now transfers the internal relocation table into the new program. This allows the compiled programs to be executed from anywhere in the Amiga's memory. o The contents of any strings used by the program are copied. o The LABEL addresses are inserted into the compiled program. These are required if your program uses gotos. (GOTO A$ for example) o If the program is of type CLI or WB, the AMOS system files are now transferred. (+40k) o The memory banks used by your program are installed into the compiled program. o Finally, the object file is closed. If you are compiling into memory, the new program file is automatically saved onto the disk. If the program is of type WB, a .info file is created for the icon. Here's an example of the way the compiler converts a single instruction into machine code: PLOT 320,100,1 becomes: move.l #1,-(a3) move.l #100,-(a3) move.l #320,-(a3) jsr Plot PACKING A COMPILED PROGRAM A compiled program (WB or CLI) can be compressed with any other compaction utility you like (including PowerPacker or Larc). Providing the new packer respects hunks in the file, everything will be fine. The only limitation is that such a program cannot be called from another compiled program with the RUN instruction. AMOS 1.3 AND COMPILER NEW ZOOM ROUTINE Your new AMOS1.3 program disk contains a memory bank file called ZOOM.ABK. This holds a new fast zoom machine language routine similar to the one used by the AMOS Sprite Editor. So if you have used the existing ZOOM routine in one of your programs, you'll have to chamge it like so: Load"Zoom.Abk",bank Now load Screen Base into A0 before use: AREG(0)=Screen Base Call bank CHAPTER 14: TROUBLESHOOTING THE COMPILER GENERATES AN OUT OF MEMORY ERROR The AMOS compiler comes complete with a range of memory conservation features. These can be activated from the compiler accessory by clicking on the RAM or Disk icons towards the top of the control panel. There are four possibilities: SOURCE DESTINATION COMMENTS RAM RAM Very fast but uses quite a lot of memory. DISK RAM Slower but consumes less space than RAM to RAM. RAM DISK Saves a fair amount of memory. Relatively slow. DISK DISK Uses a maximum of 70k internal memory, irrespective of the program. If you select the DISK to DISK option, the only limit to the size of your compiled program will be the amount of disk space. If you run out of memory, you should try each of the above options in turn. HINT: A status report of the currently available memory can be displayed at any time by simply holding down the right mouse button from the compiler accessory. If you still have problems, you'll need to reduce to size of your program, or call the compiler direct from Direct mode. See below. YOU GET AN OUT OF MEMORY ERROR WHEN YOU TRY TO RUN AN AMOS FORMAT FROM AMOS BASIC One simple way of minimising the memory overhead is to remove the memory banks used to hold your sprite, music or screen data from the main program. These banks can be loaded separately from the disk during the programs initialisation phase. This reduces the size of the compiled program significantly, saving you oodles of valuable memory. If you still run out of space, you'll need to remove everything from memory and cram the text buffer down to the bare minimum, using the Set text B. command from the AMOS Search menu. You should now compile your program from Direct mode with: AMOS>Screen Close 0 AMOS>compile"program.AMOS -Oprogram_C.AMOS -D01 -T3" This will compile 'program.AMOS' from the disk and save it under the filename 'program_C.AMOS'. You can now load the file straight into AMOS Basic and run it in the normal way. See the section on the 'Compiler extension' for details of the various options. On a one meg A500, you will now be left with an amazing 600k or so to hold your compiled programs. Hopefully, that should be more than enough! CHAPTER 15: AMOS ASSEMBLER The AMOS compiler also has an assembler allowing you to develop machine code within AMOS. The documentation for the AMOS Assembler is held in a file called 'Asm_Doc.AMOS'. This is a comment file and contains full instructions for using the assembler. The assembler is ideal for development of hybrid AMOS and assembler programs. As you probably already know, AMOS is written in 100% assembly language, so when you use an assembler for your programs main logic such as controlling aliens or solving complex maths problems for example - your program will be as fast if not faster than the top commercial programs around. to employ these techniques, commercial development can be both costly and cumbersome. But when you boot up AMOS you're sitting in one of the most powerful, best value development systems for the Amiga. Assembly in AMOS even allows you to pass variables from AMOS to the assembler with the ease. Macros can be employed using the procedures and functions of AMOS. The assembler is very fast, has an independant label bank from AMOS, full error checking telling you where and why the assembler found an error and many more features all outlined in the document file. Development is incredibly fast, you change your source code and run it immediately in the interpreted environment, carrying on in this cycle until happy with your result. When you're happy with the final assembled code in your AMOS bank, you remove your assembly language source code from the program you are developing and call the bank containing your machine code. Alternatively the assembler is fast enough to assemble at run time in the program with listing off. In the near future, through the AMOS Club, the internals of AMOS will be documented with AMOS Assembler macros showing you how to call all the routines such as bob, sprite, joystick control etc. These internal routines are the envy of many a software house who guard their macros and routines from prying eyes, which are the basis of many of the games they publish. Their libraries evolve as they write more games, so aren't as full featured and operating system legal as the AMOS internal routines. By registering and joining the AMOS Club you can gain access to these amazing routines. The AMOS Assembler can be found on the AMOS Compiler Updater disk (Assembler.AMOS). An example of a program using the assembler is also on this disk (Assembler_demo.AMOS) END.